Autogenerated HTML docs for v1.5.5.1-357-g1af8b
diff --git a/git-add.html b/git-add.html index a1fc8d0..2de91ce 100644 --- a/git-add.html +++ b/git-add.html
@@ -274,7 +274,7 @@ <div class="sectionbody"> <div class="verseblock"> <div class="content"><em>git-add</em> [-n] [-v] [-f] [--interactive | -i] [--patch | -p] [-u] [--refresh] - [--] <filepattern>…</div></div> + [--ignore-errors] [--] <filepattern>…</div></div> </div> <h2>DESCRIPTION</h2> <div class="sectionbody"> @@ -384,6 +384,16 @@ </p> </dd> <dt> +--ignore-errors +</dt> +<dd> +<p> + If some files could not be added because of errors indexing + them, do not abort the operation, but continue adding the + others. The command shall still exit with non-zero status. +</p> +</dd> +<dt> -- </dt> <dd> @@ -594,7 +604,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 09-May-2008 05:45:35 UTC +Last updated 22-May-2008 00:52:45 UTC </div> </div> </body>
diff --git a/git-add.txt b/git-add.txt index e0e730b..bb4abe2 100644 --- a/git-add.txt +++ b/git-add.txt
@@ -9,7 +9,7 @@ -------- [verse] 'git-add' [-n] [-v] [-f] [--interactive | -i] [--patch | -p] [-u] [--refresh] - [--] <filepattern>... + [--ignore-errors] [--] <filepattern>... DESCRIPTION ----------- @@ -83,6 +83,11 @@ Don't add the file(s), but only refresh their stat() information in the index. +\--ignore-errors:: + If some files could not be added because of errors indexing + them, do not abort the operation, but continue adding the + others. The command shall still exit with non-zero status. + \--:: This option can be used to separate command-line options from the list of files, (useful when filenames might be mistaken
diff --git a/git-cvsexportcommit.html b/git-cvsexportcommit.html index bdef20e..d1d10b9 100644 --- a/git-cvsexportcommit.html +++ b/git-cvsexportcommit.html
@@ -368,7 +368,8 @@ <p> Specify the location of the CVS checkout to use for the export. This option does not require GIT_DIR to be set before execution if the - current directory is within a git repository. + current directory is within a git repository. The default is the + value of <em>cvsexportcommit.cvsdir</em>. </p> </dd> <dt> @@ -381,6 +382,19 @@ </dd> </dl> </div> +<h2>CONFIGURATION</h2> +<div class="sectionbody"> +<dl> +<dt> +cvsexportcommit.cvsdir +</dt> +<dd> +<p> + The default location of the CVS checkout to use for the export. +</p> +</dd> +</dl> +</div> <h2>EXAMPLES</h2> <div class="sectionbody"> <dl> @@ -432,7 +446,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 07-Jan-2008 07:50:09 UTC +Last updated 22-May-2008 00:52:45 UTC </div> </div> </body>
diff --git a/git-cvsexportcommit.txt b/git-cvsexportcommit.txt index 9a47b4c..363c36d 100644 --- a/git-cvsexportcommit.txt +++ b/git-cvsexportcommit.txt
@@ -65,11 +65,17 @@ -w:: Specify the location of the CVS checkout to use for the export. This option does not require GIT_DIR to be set before execution if the - current directory is within a git repository. + current directory is within a git repository. The default is the + value of 'cvsexportcommit.cvsdir'. -v:: Verbose. +CONFIGURATION +------------- +cvsexportcommit.cvsdir:: + The default location of the CVS checkout to use for the export. + EXAMPLES --------
diff --git a/git-daemon.html b/git-daemon.html index 0e983ef..ad3e4bc 100644 --- a/git-daemon.html +++ b/git-daemon.html
@@ -545,7 +545,7 @@ <p> This serves <tt>git-archive --remote</tt>. It is disabled by default, but a repository can enable it by setting - <tt>daemon.uploadarchive</tt> configuration item to <tt>true</tt>. + <tt>daemon.uploadarch</tt> configuration item to <tt>true</tt>. </p> </dd> <dt> @@ -656,7 +656,7 @@ <div class="content"> <pre><tt> [daemon] uploadpack = false - uploadarchive = true</tt></pre> + uploadarch = true</tt></pre> </div></div> </dd> </dl> @@ -676,7 +676,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 07-Jan-2008 07:50:11 UTC +Last updated 22-May-2008 00:52:46 UTC </div> </div> </body>
diff --git a/git-daemon.txt b/git-daemon.txt index fd83bc7..cf261dd 100644 --- a/git-daemon.txt +++ b/git-daemon.txt
@@ -174,7 +174,7 @@ upload-archive:: This serves `git-archive --remote`. It is disabled by default, but a repository can enable it by setting - `daemon.uploadarchive` configuration item to `true`. + `daemon.uploadarch` configuration item to `true`. receive-pack:: This serves `git-send-pack` clients, allowing anonymous @@ -257,7 +257,7 @@ ---------------------------------------------------------------- [daemon] uploadpack = false - uploadarchive = true + uploadarch = true ----------------------------------------------------------------
diff --git a/git-log.html b/git-log.html index 1b7735a..45ab542 100644 --- a/git-log.html +++ b/git-log.html
@@ -945,6 +945,19 @@ -xxxxxxx... 1st on a</tt></pre> </div></div> </dd> +<dt> +--graph +</dt> +<dd> +<p> + Draw a text-based graphical representation of the commit history + on the left hand side of the output. This may cause extra lines + to be printed in between commits, in order for the graph history + to be drawn properly. +</p> +<p>This implies the <em>--topo-order</em> option by default, but the +<em>--date-order</em> option may also be specified.</p> +</dd> </dl> <h3>Diff Formatting</h3> <p>Below are listed options that control the formatting of diff output. @@ -1929,7 +1942,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 23-Apr-2008 16:08:37 UTC +Last updated 22-May-2008 00:52:46 UTC </div> </div> </body>
diff --git a/git-rev-list.html b/git-rev-list.html index d05c4c4..7a19b6d 100644 --- a/git-rev-list.html +++ b/git-rev-list.html
@@ -475,6 +475,19 @@ -xxxxxxx... 1st on a</tt></pre> </div></div> </dd> +<dt> +--graph +</dt> +<dd> +<p> + Draw a text-based graphical representation of the commit history + on the left hand side of the output. This may cause extra lines + to be printed in between commits, in order for the graph history + to be drawn properly. +</p> +<p>This implies the <em>--topo-order</em> option by default, but the +<em>--date-order</em> option may also be specified.</p> +</dd> </dl> <h3>Diff Formatting</h3> <p>Below are listed options that control the formatting of diff output. @@ -1211,7 +1224,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 09-Apr-2008 09:38:27 UTC +Last updated 22-May-2008 00:52:46 UTC </div> </div> </body>
diff --git a/git-rev-parse.html b/git-rev-parse.html index b3f7a95..527597b 100644 --- a/git-rev-parse.html +++ b/git-rev-parse.html
@@ -851,6 +851,40 @@ eval `echo "$OPTS_SPEC" | git-rev-parse --parseopt -- "$@" || echo exit $?`</tt></pre> </div></div> </div> +<h2>EXAMPLES</h2> +<div class="sectionbody"> +<ul> +<li> +<p> +Print the object name of the current commit: +</p> +<div class="listingblock"> +<div class="content"> +<pre><tt>$ git rev-parse --verify HEAD</tt></pre> +</div></div> +</li> +<li> +<p> +Print the commit object name from the revision in the $REV shell variable: +</p> +<div class="listingblock"> +<div class="content"> +<pre><tt>$ git rev-parse --verify $REV</tt></pre> +</div></div> +<p>This will error out if $REV is empty or not a valid revision.</p> +</li> +<li> +<p> +Same as above: +</p> +<div class="listingblock"> +<div class="content"> +<pre><tt>$ git rev-parse --default master --verify $REV</tt></pre> +</div></div> +<p>but if $REV is empty, the commit object name from master will be printed.</p> +</li> +</ul> +</div> <h2>Author</h2> <div class="sectionbody"> <p>Written by Linus Torvalds <torvalds@osdl.org> . @@ -866,7 +900,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 14-May-2008 22:24:42 UTC +Last updated 22-May-2008 00:52:47 UTC </div> </div> </body>
diff --git a/git-rev-parse.txt b/git-rev-parse.txt index b6b2fe9..69599ff 100644 --- a/git-rev-parse.txt +++ b/git-rev-parse.txt
@@ -378,6 +378,31 @@ eval `echo "$OPTS_SPEC" | git-rev-parse --parseopt -- "$@" || echo exit $?` ------------ +EXAMPLES +-------- + +* Print the object name of the current commit: ++ +------------ +$ git rev-parse --verify HEAD +------------ + +* Print the commit object name from the revision in the $REV shell variable: ++ +------------ +$ git rev-parse --verify $REV +------------ ++ +This will error out if $REV is empty or not a valid revision. + +* Same as above: ++ +------------ +$ git rev-parse --default master --verify $REV +------------ ++ +but if $REV is empty, the commit object name from master will be printed. + Author ------
diff --git a/git-svn.html b/git-svn.html index 2db4ab8..6cebaf7 100644 --- a/git-svn.html +++ b/git-svn.html
@@ -625,7 +625,8 @@ <p> Recursively finds the svn:ignore property on directories and creates matching .gitignore files. The resulting files are staged to - be committed, but are not committed. + be committed, but are not committed. Use -r/--revision to refer to a + specfic revision. </p> </dd> <dt> @@ -665,6 +666,34 @@ <em>URL:</em> field. </p> </dd> +<dt> +<em>proplist</em> +</dt> +<dd> +<p> + Lists the properties stored in the Subversion repository about a + given file or directory. Use -r/--revision to refer to a specific + Subversion revision. +</p> +</dd> +<dt> +<em>propget</em> +</dt> +<dd> +<p> + Gets the Subversion property given as the first argument, for a + file. A specific revision can be specified with -r/--revision. +</p> +</dd> +<dt> +<em>show-externals</em> +</dt> +<dd> +<p> + Shows the Subversion externals. Use -r/--revision to specify a + specific revision. +</p> +</dd> </dl> </div> <h2>OPTIONS</h2> @@ -1120,7 +1149,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 12-May-2008 00:29:22 UTC +Last updated 22-May-2008 00:52:47 UTC </div> </div> </body>
diff --git a/git-svn.txt b/git-svn.txt index c6b56b4..3eae1eb 100644 --- a/git-svn.txt +++ b/git-svn.txt
@@ -196,10 +196,10 @@ independently of git-svn functions. 'create-ignore':: - Recursively finds the svn:ignore property on directories and creates matching .gitignore files. The resulting files are staged to - be committed, but are not committed. + be committed, but are not committed. Use -r/--revision to refer to a + specfic revision. 'show-ignore':: Recursively finds and lists the svn:ignore property on @@ -223,6 +223,19 @@ argument. Use the --url option to output only the value of the 'URL:' field. +'proplist':: + Lists the properties stored in the Subversion repository about a + given file or directory. Use -r/--revision to refer to a specific + Subversion revision. + +'propget':: + Gets the Subversion property given as the first argument, for a + file. A specific revision can be specified with -r/--revision. + +'show-externals':: + Shows the Subversion externals. Use -r/--revision to specify a + specific revision. + -- OPTIONS
diff --git a/rev-list-options.txt b/rev-list-options.txt index 2648a55..ce6a101 100644 --- a/rev-list-options.txt +++ b/rev-list-options.txt
@@ -75,6 +75,16 @@ -xxxxxxx... 1st on a ----------------------------------------------------------------------- +--graph:: + + Draw a text-based graphical representation of the commit history + on the left hand side of the output. This may cause extra lines + to be printed in between commits, in order for the graph history + to be drawn properly. ++ +This implies the '--topo-order' option by default, but the +'--date-order' option may also be specified. + Diff Formatting ~~~~~~~~~~~~~~~
diff --git a/technical/api-history-graph.html b/technical/api-history-graph.html new file mode 100644 index 0000000..a0e0231 --- /dev/null +++ b/technical/api-history-graph.html
@@ -0,0 +1,508 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" + "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> +<meta name="generator" content="AsciiDoc 7.0.2" /> +<style type="text/css"> +/* Debug borders */ +p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 { +/* + border: 1px solid red; +*/ +} + +body { + margin: 1em 5% 1em 5%; +} + +a { color: blue; } +a:visited { color: fuchsia; } + +em { + font-style: italic; +} + +strong { + font-weight: bold; +} + +tt { + color: navy; +} + +h1, h2, h3, h4, h5, h6 { + color: #527bbd; + font-family: sans-serif; + margin-top: 1.2em; + margin-bottom: 0.5em; + line-height: 1.3; +} + +h1 { + border-bottom: 2px solid silver; +} +h2 { + border-bottom: 2px solid silver; + padding-top: 0.5em; +} + +div.sectionbody { + font-family: serif; + margin-left: 0; +} + +hr { + border: 1px solid silver; +} + +p { + margin-top: 0.5em; + margin-bottom: 0.5em; +} + +pre { + padding: 0; + margin: 0; +} + +span#author { + color: #527bbd; + font-family: sans-serif; + font-weight: bold; + font-size: 1.2em; +} +span#email { +} +span#revision { + font-family: sans-serif; +} + +div#footer { + font-family: sans-serif; + font-size: small; + border-top: 2px solid silver; + padding-top: 0.5em; + margin-top: 4.0em; +} +div#footer-text { + float: left; + padding-bottom: 0.5em; +} +div#footer-badges { + float: right; + padding-bottom: 0.5em; +} + +div#preamble, +div.tableblock, div.imageblock, div.exampleblock, div.verseblock, +div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock, +div.admonitionblock { + margin-right: 10%; + margin-top: 1.5em; + margin-bottom: 1.5em; +} +div.admonitionblock { + margin-top: 2.5em; + margin-bottom: 2.5em; +} + +div.content { /* Block element content. */ + padding: 0; +} + +/* Block element titles. */ +div.title, caption.title { + font-family: sans-serif; + font-weight: bold; + text-align: left; + margin-top: 1.0em; + margin-bottom: 0.5em; +} +div.title + * { + margin-top: 0; +} + +td div.title:first-child { + margin-top: 0.0em; +} +div.content div.title:first-child { + margin-top: 0.0em; +} +div.content + div.title { + margin-top: 0.0em; +} + +div.sidebarblock > div.content { + background: #ffffee; + border: 1px solid silver; + padding: 0.5em; +} + +div.listingblock > div.content { + border: 1px solid silver; + background: #f4f4f4; + padding: 0.5em; +} + +div.quoteblock > div.content { + padding-left: 2.0em; +} +div.quoteblock .attribution { + text-align: right; +} + +div.admonitionblock .icon { + vertical-align: top; + font-size: 1.1em; + font-weight: bold; + text-decoration: underline; + color: #527bbd; + padding-right: 0.5em; +} +div.admonitionblock td.content { + padding-left: 0.5em; + border-left: 2px solid silver; +} + +div.exampleblock > div.content { + border-left: 2px solid silver; + padding: 0.5em; +} + +div.verseblock div.content { + white-space: pre; +} + +div.imageblock div.content { padding-left: 0; } +div.imageblock img { border: 1px solid silver; } +span.image img { border-style: none; } + +dl { + margin-top: 0.8em; + margin-bottom: 0.8em; +} +dt { + margin-top: 0.5em; + margin-bottom: 0; + font-style: italic; +} +dd > *:first-child { + margin-top: 0; +} + +ul, ol { + list-style-position: outside; +} +ol.olist2 { + list-style-type: lower-alpha; +} + +div.tableblock > table { + border-color: #527bbd; + border-width: 3px; +} +thead { + font-family: sans-serif; + font-weight: bold; +} +tfoot { + font-weight: bold; +} + +div.hlist { + margin-top: 0.8em; + margin-bottom: 0.8em; +} +td.hlist1 { + vertical-align: top; + font-style: italic; + padding-right: 0.8em; +} +td.hlist2 { + vertical-align: top; +} + +@media print { + div#footer-badges { display: none; } +} +/* Workarounds for IE6's broken and incomplete CSS2. */ + +div.sidebar-content { + background: #ffffee; + border: 1px solid silver; + padding: 0.5em; +} +div.sidebar-title, div.image-title { + font-family: sans-serif; + font-weight: bold; + margin-top: 0.0em; + margin-bottom: 0.5em; +} + +div.listingblock div.content { + border: 1px solid silver; + background: #f4f4f4; + padding: 0.5em; +} + +div.quoteblock-content { + padding-left: 2.0em; +} + +div.exampleblock-content { + border-left: 2px solid silver; + padding-left: 0.5em; +} +</style> +<title>history graph API</title> +</head> +<body> +<div id="header"> +<h1>history graph API</h1> +</div> +<div id="preamble"> +<div class="sectionbody"> +<p>The graph API is used to draw a text-based representation of the commit +history. The API generates the graph in a line-by-line fashion.</p> +</div> +</div> +<h2>Functions</h2> +<div class="sectionbody"> +<p>Core functions:</p> +<ul> +<li> +<p> +<tt>graph_init()</tt> creates a new <tt>struct git_graph</tt> +</p> +</li> +<li> +<p> +<tt>graph_release()</tt> destroys a <tt>struct git_graph</tt>, and frees the memory + associated with it. +</p> +</li> +<li> +<p> +<tt>graph_update()</tt> moves the graph to a new commit. +</p> +</li> +<li> +<p> +<tt>graph_next_line()</tt> outputs the next line of the graph into a strbuf. It + does not add a terminating newline. +</p> +</li> +<li> +<p> +<tt>graph_padding_line()</tt> outputs a line of vertical padding in the graph. It + is similar to <tt>graph_next_line()</tt>, but is guaranteed to never print the line + containing the current commit. Where <tt>graph_next_line()</tt> would print the + commit line next, <tt>graph_padding_line()</tt> prints a line that simply extends + all branch lines downwards one row, leaving their positions unchanged. +</p> +</li> +<li> +<p> +<tt>graph_is_commit_finished()</tt> determines if the graph has output all lines + necessary for the current commit. If <tt>graph_update()</tt> is called before all + lines for the current commit have been printed, the next call to + <tt>graph_next_line()</tt> will output an ellipsis, to indicate that a portion of + the graph was omitted. +</p> +</li> +</ul> +<p>The following utility functions are wrappers around <tt>graph_next_line()</tt> and +<tt>graph_is_commit_finished()</tt>. They always print the output to stdout. +They can all be called with a NULL graph argument, in which case no graph +output will be printed.</p> +<ul> +<li> +<p> +<tt>graph_show_commit()</tt> calls <tt>graph_next_line()</tt> until it returns non-zero. + This prints all graph lines up to, and including, the line containing this + commit. Output is printed to stdout. The last line printed does not contain + a terminating newline. This should not be called if the commit line has + already been printed, or it will loop forever. +</p> +</li> +<li> +<p> +<tt>graph_show_oneline()</tt> calls <tt>graph_next_line()</tt> and prints the result to + stdout. The line printed does not contain a terminating newline. +</p> +</li> +<li> +<p> +<tt>graph_show_padding()</tt> calls <tt>graph_padding_line()</tt> and prints the result to + stdout. The line printed does not contain a terminating newline. +</p> +</li> +<li> +<p> +<tt>graph_show_remainder()</tt> calls <tt>graph_next_line()</tt> until + <tt>graph_is_commit_finished()</tt> returns non-zero. Output is printed to stdout. + The last line printed does not contain a terminating newline. Returns 1 if + output was printed, and 0 if no output was necessary. +</p> +</li> +<li> +<p> +<tt>graph_show_strbuf()</tt> prints the specified strbuf to stdout, prefixing all + lines but the first with a graph line. The caller is responsible for + ensuring graph output for the first line has already been printed to stdout. + (This can be done with <tt>graph_show_commit()</tt> or <tt>graph_show_oneline()</tt>.) If + a NULL graph is supplied, the strbuf is printed as-is. +</p> +</li> +<li> +<p> +<tt>graph_show_commit_msg()</tt> is similar to <tt>graph_show_strbuf()</tt>, but it also + prints the remainder of the graph, if more lines are needed after the strbuf + ends. It is better than directly calling <tt>graph_show_strbuf()</tt> followed by + <tt>graph_show_remainder()</tt> since it properly handles buffers that do not end in + a terminating newline. The output printed by <tt>graph_show_commit_msg()</tt> will + end in a newline if and only if the strbuf ends in a newline. +</p> +</li> +</ul> +</div> +<h2>Data structure</h2> +<div class="sectionbody"> +<p><tt>struct git_graph</tt> is an opaque data type used to store the current graph +state.</p> +</div> +<h2>Calling sequence</h2> +<div class="sectionbody"> +<ul> +<li> +<p> +Create a <tt>struct git_graph</tt> by calling <tt>graph_init()</tt>. When using the + revision walking API, this is done automatically by <tt>setup_revisions()</tt> if + the <em>—graph</em> option is supplied. +</p> +</li> +<li> +<p> +Use the revision walking API to walk through a group of contiguous commits. + The <tt>get_revision()</tt> function automatically calls <tt>graph_update()</tt> each time + it is invoked. +</p> +</li> +<li> +<p> +For each commit, call <tt>graph_next_line()</tt> repeatedly, until + <tt>graph_is_commit_finished()</tt> returns non-zero. Each call go + <tt>graph_next_line()</tt> will output a single line of the graph. The resulting + lines will not contain any newlines. <tt>graph_next_line()</tt> returns 1 if the + resulting line contains the current commit, or 0 if this is merely a line + needed to adjust the graph before or after the current commit. This return + value can be used to determine where to print the commit summary information + alongside the graph output. +</p> +</li> +</ul> +</div> +<h2>Limitations</h2> +<div class="sectionbody"> +<ul> +<li> +<p> +<tt>graph_update()</tt> must be called with commits in topological order. It should + not be called on a commit if it has already been invoked with an ancestor of + that commit, or the graph output will be incorrect. +</p> +</li> +<li> +<p> +<tt>graph_update()</tt> must be called on a contiguous group of commits. If + <tt>graph_update()</tt> is called on a particular commit, it should later be called + on all parents of that commit. Parents must not be skipped, or the graph + output will appear incorrect. +</p> +<p><tt>graph_update()</tt> may be used on a pruned set of commits only if the parent list +has been rewritten so as to include only ancestors from the pruned set.</p> +</li> +<li> +<p> +The graph API does not currently support reverse commit ordering. In + order to implement reverse ordering, the graphing API needs an + (efficient) mechanism to find the children of a commit. +</p> +</li> +</ul> +</div> +<h2>Sample usage</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre><tt>struct commit *commit; +struct git_graph *graph = graph_init(); + +while ((commit = get_revision(opts)) != NULL) { + graph_update(graph, commit); + while (!graph_is_commit_finished(graph)) + { + struct strbuf sb; + int is_commit_line; + + strbuf_init(&sb, 0); + is_commit_line = graph_next_line(graph, &sb); + fputs(sb.buf, stdout); + + if (is_commit_line) + log_tree_commit(opts, commit); + else + putchar(opts->diffopt.line_termination); + } +} + +graph_release(graph);</tt></pre> +</div></div> +</div> +<h2>Sample output</h2> +<div class="sectionbody"> +<p>The following is an example of the output from the graph API. This output does +not include any commit summary information—callers are responsible for +outputting that information, if desired.</p> +<div class="listingblock"> +<div class="content"> +<pre><tt>* +* +M +|\ +* | +| | * +| \ \ +| \ \ +M-. \ \ +|\ \ \ \ +| | * | | +| | | | | * +| | | | | * +| | | | | M +| | | | | |\ +| | | | | | * +| * | | | | | +| | | | | M \ +| | | | | |\ | +| | | | * | | | +| | | | * | | | +* | | | | | | | +| |/ / / / / / +|/| / / / / / +* | | | | | | +|/ / / / / / +* | | | | | +| | | | | * +| | | | |/ +| | | | *</tt></pre> +</div></div> +</div> +<div id="footer"> +<div id="footer-text"> +Last updated 22-May-2008 00:52:48 UTC +</div> +</div> +</body> +</html> diff --git a/technical/api-history-graph.txt b/technical/api-history-graph.txt new file mode 100644 index 0000000..ce1c08e --- /dev/null +++ b/technical/api-history-graph.txt
@@ -0,0 +1,179 @@ +history graph API +================= + +The graph API is used to draw a text-based representation of the commit +history. The API generates the graph in a line-by-line fashion. + +Functions +--------- + +Core functions: + +* `graph_init()` creates a new `struct git_graph` + +* `graph_release()` destroys a `struct git_graph`, and frees the memory + associated with it. + +* `graph_update()` moves the graph to a new commit. + +* `graph_next_line()` outputs the next line of the graph into a strbuf. It + does not add a terminating newline. + +* `graph_padding_line()` outputs a line of vertical padding in the graph. It + is similar to `graph_next_line()`, but is guaranteed to never print the line + containing the current commit. Where `graph_next_line()` would print the + commit line next, `graph_padding_line()` prints a line that simply extends + all branch lines downwards one row, leaving their positions unchanged. + +* `graph_is_commit_finished()` determines if the graph has output all lines + necessary for the current commit. If `graph_update()` is called before all + lines for the current commit have been printed, the next call to + `graph_next_line()` will output an ellipsis, to indicate that a portion of + the graph was omitted. + +The following utility functions are wrappers around `graph_next_line()` and +`graph_is_commit_finished()`. They always print the output to stdout. +They can all be called with a NULL graph argument, in which case no graph +output will be printed. + +* `graph_show_commit()` calls `graph_next_line()` until it returns non-zero. + This prints all graph lines up to, and including, the line containing this + commit. Output is printed to stdout. The last line printed does not contain + a terminating newline. This should not be called if the commit line has + already been printed, or it will loop forever. + +* `graph_show_oneline()` calls `graph_next_line()` and prints the result to + stdout. The line printed does not contain a terminating newline. + +* `graph_show_padding()` calls `graph_padding_line()` and prints the result to + stdout. The line printed does not contain a terminating newline. + +* `graph_show_remainder()` calls `graph_next_line()` until + `graph_is_commit_finished()` returns non-zero. Output is printed to stdout. + The last line printed does not contain a terminating newline. Returns 1 if + output was printed, and 0 if no output was necessary. + +* `graph_show_strbuf()` prints the specified strbuf to stdout, prefixing all + lines but the first with a graph line. The caller is responsible for + ensuring graph output for the first line has already been printed to stdout. + (This can be done with `graph_show_commit()` or `graph_show_oneline()`.) If + a NULL graph is supplied, the strbuf is printed as-is. + +* `graph_show_commit_msg()` is similar to `graph_show_strbuf()`, but it also + prints the remainder of the graph, if more lines are needed after the strbuf + ends. It is better than directly calling `graph_show_strbuf()` followed by + `graph_show_remainder()` since it properly handles buffers that do not end in + a terminating newline. The output printed by `graph_show_commit_msg()` will + end in a newline if and only if the strbuf ends in a newline. + +Data structure +-------------- +`struct git_graph` is an opaque data type used to store the current graph +state. + +Calling sequence +---------------- + +* Create a `struct git_graph` by calling `graph_init()`. When using the + revision walking API, this is done automatically by `setup_revisions()` if + the '--graph' option is supplied. + +* Use the revision walking API to walk through a group of contiguous commits. + The `get_revision()` function automatically calls `graph_update()` each time + it is invoked. + +* For each commit, call `graph_next_line()` repeatedly, until + `graph_is_commit_finished()` returns non-zero. Each call go + `graph_next_line()` will output a single line of the graph. The resulting + lines will not contain any newlines. `graph_next_line()` returns 1 if the + resulting line contains the current commit, or 0 if this is merely a line + needed to adjust the graph before or after the current commit. This return + value can be used to determine where to print the commit summary information + alongside the graph output. + +Limitations +----------- + +* `graph_update()` must be called with commits in topological order. It should + not be called on a commit if it has already been invoked with an ancestor of + that commit, or the graph output will be incorrect. + +* `graph_update()` must be called on a contiguous group of commits. If + `graph_update()` is called on a particular commit, it should later be called + on all parents of that commit. Parents must not be skipped, or the graph + output will appear incorrect. ++ +`graph_update()` may be used on a pruned set of commits only if the parent list +has been rewritten so as to include only ancestors from the pruned set. + +* The graph API does not currently support reverse commit ordering. In + order to implement reverse ordering, the graphing API needs an + (efficient) mechanism to find the children of a commit. + +Sample usage +------------ + +------------ +struct commit *commit; +struct git_graph *graph = graph_init(); + +while ((commit = get_revision(opts)) != NULL) { + graph_update(graph, commit); + while (!graph_is_commit_finished(graph)) + { + struct strbuf sb; + int is_commit_line; + + strbuf_init(&sb, 0); + is_commit_line = graph_next_line(graph, &sb); + fputs(sb.buf, stdout); + + if (is_commit_line) + log_tree_commit(opts, commit); + else + putchar(opts->diffopt.line_termination); + } +} + +graph_release(graph); +------------ + +Sample output +------------- + +The following is an example of the output from the graph API. This output does +not include any commit summary information--callers are responsible for +outputting that information, if desired. + +------------ +* +* +M +|\ +* | +| | * +| \ \ +| \ \ +M-. \ \ +|\ \ \ \ +| | * | | +| | | | | * +| | | | | * +| | | | | M +| | | | | |\ +| | | | | | * +| * | | | | | +| | | | | M \ +| | | | | |\ | +| | | | * | | | +| | | | * | | | +* | | | | | | | +| |/ / / / / / +|/| / / / / / +* | | | | | | +|/ / / / / / +* | | | | | +| | | | | * +| | | | |/ +| | | | * +------------ diff --git a/technical/api-index.html b/technical/api-index.html index 58fc703..6ae6947 100644 --- a/technical/api-index.html +++ b/technical/api-index.html
@@ -308,6 +308,11 @@ </li> <li> <p> +<a href="api-history-graph.html">history graph API</a> +</p> +</li> +<li> +<p> <a href="api-in-core-index.html">in-core index API</a> </p> </li> @@ -377,7 +382,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 20-Feb-2008 10:44:10 UTC +Last updated 22-May-2008 00:52:49 UTC </div> </div> </body>
diff --git a/technical/api-index.txt b/technical/api-index.txt index 6c272fc..4a1190d 100644 --- a/technical/api-index.txt +++ b/technical/api-index.txt
@@ -15,6 +15,7 @@ * link:api-gitattributes.html[gitattributes API] * link:api-grep.html[grep API] * link:api-hash.html[hash API] +* link:api-history-graph.html[history graph API] * link:api-in-core-index.html[in-core index API] * link:api-lockfile.html[lockfile API] * link:api-object-access.html[object access API]
